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Abstract 


This specification defines a profile for issuing OAuth 2.0 access tokens in JSON Web Token (JWT) 
format. Authorization servers and resource servers from different vendors can leverage this 
profile to issue and consume access tokens in an interoperable manner. 
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1. Introduction 


The original OAuth 2.0 Authorization Framework [RFC6749] specification does not mandate any 
specific format for access tokens. While that remains perfectly appropriate for many important 
scenarios, in-market use has shown that many commercial OAuth 2.0 implementations elected to 
issue access tokens using a format that can be parsed and validated by resource servers directly, 
without further authorization server involvement. The approach is particularly common in 
topologies where the authorization server and resource server are not co-located, are not run by 
the same entity, or are otherwise separated by some boundary. At the time of writing, many 
commercial implementations leverage the JSON Web Token (JWT) [RFC7519] format. 


Many vendor-specific JWT access tokens share the same functional layout, using JWT claims to 
convey the information needed to support a common set of use cases: token validation, 
transporting authorization information in the form of scopes and entitlements, carrying identity 
information about the subject, and so on. The differences are mostly confined to the claim names 
and syntax used to represent the same entities, suggesting that interoperability could be easily 
achieved by standardizing a common set of claims and validation rules. 


The assumption that access tokens are associated with specific information doesn't appear only 
in commercial implementations. Various specifications in the OAuth 2.0 family (suchas resource 
indicators [RFC8707], OAuth 2.0 bearer token usage [RFC6750], and others) postulate the presence 
of scoping mechanisms, such as an audience, in access tokens. The family of specifications 
associated with introspection also indirectly suggests a fundamental set of information that 
access tokens are expected to carry or at least be associated with. 


This specification aims to provide a standardized and interoperable profile as an alternative to 
the proprietary JWT access token layouts going forward. Besides defining a common set of 
mandatory and optional claims, the profile provides clear indications on how authorization 
request parameters determine the content of the issued JWT access token, how an authorization 
server can publish metadata relevant to the JWT access tokens it issues, and how a resource 
server should validate incoming JWT access tokens. 


Finally, this specification provides security and privacy considerations meant to prevent 
common mistakes and anti-patterns that are likely to occur in naive use of the JWT format to 
represent access tokens. 


Please note: Although both this document and [RFC7523] use JSON Web Tokens in the context 
of the OAuth2 framework, the two specifications differ in both intent and mechanics. Whereas 
[RFC7523] defines how a JWT Bearer Token can be used to request an access token, this 
document describes how to encode access tokens in JWT format. 
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1.1. Requirements Notation and Conventions 


The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", 
"RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be 
interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 
capitals, as shown here. 


1.2. Terminology 


JWT access token: An OAuth 2.0 access token encoded in JWT format and complying with the 
requirements described in this specification. 


wou wou oom 


This specification uses the terms "access token", "refresh token", "authorization server", "resource 


"n "n "n "on 


server", "authorization endpoint", "authorization request", "authorization response", "token 
endpoint", "grant type", "access token request", "access token response", and "client" defined by 


The OAuth 2.0 Authorization Framework [RFC6749]. 


2. JWT Access Token Header and Data Structure 


2.1. Header 


JWT access tokens MUST be signed. Although JWT access tokens can use any signing algorithm, 
use of asymmetric cryptography is RECOMMENDED as it simplifies the process of acquiring 
validation information for resource servers (see Section 4). JWT access tokens MUST NOT use 
"none" as the signing algorithm. See Section 4 for more details. 


Authorization servers and resource servers conforming to this specification MUST include RS256 
(as defined in [RFC7518]) among their supported signature algorithms. 


This specification registers the "application/at+jwt" media type, which can be used to indicate that 
the content is a JWT access token. JWT access tokens MUST include this media type in the "typ" 
header parameter to explicitly declare that the JWT represents an access token complying with 
this profile. Per the definition of "typ" in Section 4.1.9 of [RFC7515], it is RECOMMENDED that the 
“application/" prefix be omitted. Therefore, the "typ" value used SHOULD be "at+jwt". See the 
Security Considerations section for details on the importance of preventing OpenID Connect ID 
Tokens (as defined by Section 2 of [OpenID.Core]) from being accepted as access tokens by 
resource servers implementing this profile. 


2.2. Data Structure 


The following claims are used in the JWT access token data structure. 


iss REQUIRED - as defined in Section 4.1.1 of [RFC7519]. 


exp REQUIRED - as defined in Section 4.1.4 of [RFC7519]. 
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aud REQUIRED - as defined in Section 4.1.3 of [RFC7519]. See Section 3 for indications on how an 
authorization server should determine the value of "aud" depending on the request. 


sub REQUIRED - as defined in Section 4.1.2 of [RFC7519]. In cases of access tokens obtained 
through grants where a resource owner is involved, such as the authorization code grant, the 
value of "sub" SHOULD correspond to the subject identifier of the resource owner. In cases of 
access tokens obtained through grants where no resource owner is involved, such as the client 
credentials grant, the value of "sub" SHOULD correspond to an identifier the authorization 
server uses to indicate the client application. See Section 5 for more details on this scenario. 
Also, see Section 6 for a discussion about how different choices in assigning "sub" values can 
impact privacy. 


client_id REQUIRED - as defined in Section 4.3 of [RFC8693]. 


iat REQUIRED - as defined in Section 4.1.6 of [RFC7519]. This claim identifies the time at which the 
JWT access token was issued. 


jti REQUIRED - as defined in Section 4.1.7 of [RFC7519]. 


2.2.1. Authentication Information Claims 


The claims listed in this section MAY be issued in the context of authorization grants involving the 
resource owner and reflect the types and strength of authentication in the access token that the 
authentication server enforced prior to returning the authorization response to the client. Their 
values are fixed and remain the same across all access tokens that derive from a given 
authorization response, whether the access token was obtained directly in the response (e.g., via 
the implicit flow) or after one or more token exchanges (e.g., obtaining a fresh access token using 
a refresh token or exchanging one access token for another via [RFC8693] procedures). 


auth_time OPTIONAL - as defined in Section 2 of [OpenID.Core]. 
acr OPTIONAL - as defined in Section 2 of [OpenID.Core]. 


amr OPTIONAL - as defined in Section 2 of [OpenID.Core]. 


2.2.2. Identity Claims 


In the context of authorization grants involving the resource owner, commercial authorization 
servers will often include resource owner attributes directly in access tokens so that resource 
servers can consume them directly for authorization or other purposes without any further 
round trips to introspection ([RFC7662]) or UserInfo ([OpenID.Core]) endpoints. This is 
particularly common in scenarios where the client and the resource server belong to the same 
entity and are part of the same solution, as is the case for first-party clients invoking their own 
backend API. 


This profile does not introduce any mechanism for a client to directly request the presence of 
specific claims in JWT access tokens, as the authorization server can determine what additional 
claims are required by a particular resource server by taking the client_id of the client and the 
"scope" and the "resource" parameters included in the request into consideration. 
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Any additional identity attribute whose semantic is well described by an entry in the "JSON Web 
Token (JWT)" IANA registry introduced in [RFC7519] SHOULD be encoded using the corresponding 
claim name, if that attribute is to be included in the JWT access token. Note that the JWT IANA 
registry includes the claims found in Section 5.1 of [OpenID.Core]. 


Authorization servers MAY return arbitrary attributes not defined in any existing specification, as 
long as the corresponding claim names are collision resistant or the access tokens are meant to 
be used only within a private subsystem. Please refer to Sections 4.2 and 4.3 of [RFC7519] for 
details. 


Authorization servers including resource owner attributes in JWT access tokens need to exercise 
care and verify that all privacy requirements are met, as discussed in Section 6. 


2.2.3. Authorization Claims 


If an authorization request includes a scope parameter, the corresponding issued JWT access 
token SHOULD include a "scope" claim as defined in Section 4.2 of [RFC8693]. 


All the individual scope strings in the "scope" claim MUST have meaning for the resources 
indicated in the "aud" claim. See Section 5 for more considerations about the relationship 
between scope strings and resources indicated by the "aud" claim. 


2.2.3.1. Claims for Authorization Outside of Delegation Scenarios 


Many authorization servers embed authorization attributes that go beyond the delegated 
scenarios described by [RFC7519] in the access tokens they issue. Typical examples include 
resource owner memberships in roles and groups that are relevant to the resource being 
accessed, entitlements assigned to the resource owner for the targeted resource that the 
authorization server knows about, and so on. 


An authorization server wanting to include such attributes in a JWT access token SHOULD use the 
"groups", "roles", and "entitlements" attributes of the "User" resource schema defined by Section 
4.1.2 of [RFC7643]) as claim types. 


Authorization servers SHOULD encode the corresponding claim values according to the guidance 
defined in [RFC7643]. In particular, a non-normative example of a "groups" attribute can be 
found in Section 8.2 of [RFC7643]. No specific vocabulary is provided for "roles" and 
"entitlements". 


Section 7.2.1 of this document provides entries for registering "groups", "roles", and "entitlements" 
attributes from [RFC7643] as claim types to be used in this profile. 


3. Requesting a JWT Access Token 


An authorization server can issue a JWT access token in response to any authorization grant 
defined by [RFC6749] and subsequent extensions meant to result in an access token. 


If the request includes a "resource" parameter (as defined in [RFC8707]), the resulting JWT access 
token "aud" claim SHOULD have the same value as the "resource" parameter in the request. 
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Example request below: 


GET /as/authorization.oauth2?response_type=code 
&client_id=s6BhdRkqt3 
&state=xyz 
&scope=openid%20profile%20reademail 
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 
&resource=https%3A%2F%2Frs.example.com%2F HTTP/1.1 
Host: authorization-server.example.com 


Figure 1: Authorization Request with Resource and Scope Parameters 
Once redeemed, the code obtained from the request above will result in a JWT access token in the 


form shown below: 


Header: 


{"typ":"at+JWT", "alg" :"RS256", "kid": "RjEwOw0A" } 


Claims: 

{ 
"iss": "https://authorization-server.example.com/", 
"sub": "5ba552d67", 
"aud": "https://rs.example.com/", 
"exp": 1639528912, 
"iat": 1618354890, 
"jti" : "dbe39bf3a3ba4238a513f51d6e1691c4", 
"client_id": "s6BhdRkqt3", 
"scope": "openid profile reademail" 

} 


Figure 2: The Header and JWT Claims Set of a JWT Access Token 


The authorization server MUST NOT issue a JWT access token if the authorization granted by the 
token would be ambiguous. See Section 5 for more details about common cases that might lead to 
ambiguity and strategies an authorization server can enact to prevent them. 


If the request does not include a "resource" parameter, the authorization server MUST use a 
default resource indicator in the "aud" claim. If a "scope" parameter is present in the request, the 
authorization server SHOULD use it to infer the value of the default resource indicator to be used 
in the "aud" claim. The mechanism through which scopes are associated with default resource 
indicator values is outside the scope of this specification. If the values in the "scope" parameter 
refer to different default resource indicator values, the authorization server SHOULD reject the 
request with "invalid_scope" as described in Section 4.1.2.1 of [RFC6749]. 
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4. Validating JWT Access Tokens 


For the purpose of facilitating validation data retrieval, it is RECOMMENDED here that 
authorization servers sign JWT access tokens with an asymmetric algorithm. 


Authorization servers SHOULD use OAuth 2.0 Authorization Server Metadata [RFC8414] to 
advertise to resource servers their signing keys via "}wks_uri" and what "iss" claim value to expect 
via the "issuer" metadata value. Alternatively, authorization servers implementing OpenID 
Connect MAY use the OpenID Connect discovery [OpenID.Discovery] document for the same 
purpose. If an authorization server supports both OAuth 2.0 Authorization Server Metadata and 
OpenID Connect discovery, the values provided MUST be consistent across the two publication 
methods. 


An authorization server MAY elect to use different keys to sign OpenID Connect ID Tokens and 
JWT access tokens. This specification does not provide a mechanism for identifying a specific key 
as the one used to sign JWT access tokens. An authorization server can sign JWT access tokens 
with any of the keys advertised via authorization server (AS) metadata or OpenID Connect 
discovery. See Section 5 for further guidance on security implications. 


Resource servers receiving a JWT access token MUST validate it in the following manner. 


e The resource server MUST verify that the "typ" header value is "at+jwt" or "application/at+jwt" 
and reject tokens carrying any other value. 


e If the JWT access token is encrypted, decrypt it using the keys and algorithms that the 
resource server specified during registration. If encryption was negotiated with the 
authorization server at registration time and the incoming JWT access token is not 
encrypted, the resource server SHOULD reject it. 


e The issuer identifier for the authorization server (which is typically obtained during 
discovery) MUST exactly match the value of the "iss" claim. 


° The resource server MUST validate that the "aud" claim contains a resource indicator value 
corresponding to an identifier the resource server expects for itself. The JWT access token 
MUST be rejected if "aud" does not contain a resource indicator of the current resource server 
as a valid audience. 


e The resource server MUST validate the signature of all incoming JWT access tokens according 
to [RFC7515] using the algorithm specified in the JWT "alg" Header Parameter. The resource 
server MUST reject any JWT in which the value of "alg" is "none". The resource server MUST use 
the keys provided by the authorization server. 


e The current time MUST be before the time represented by the "exp" claim. Implementers MAY 
provide for some small leeway, usually no more than a few minutes, to account for clock 
skew. 
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The resource server MUST handle errors as described in Section 3.1 of [RFC6750]. In particular, in 
case of any failure in the validation checks listed above, the authorization server response MUST 
include the error code "invalid_token". Please note that this requirement does not prevent JWT 
access tokens from using authentication schemes other than "Bearer". 


If the JWT access token includes authorization claims as described in Section 2.2.3, the resource 
server SHOULD use them in combination with any other contextual information available to 
determine whether the current call should be authorized or rejected. Details about how a resource 
server performs those checks is beyond the scope of this profile specification. 


5. Security Considerations 


The JWT access token data layout described here is very similar to that of the id_token as defined 
by [OpenID.Core]. The explicit typing required in this profile, in line with the recommendations in 
[RFC8725], helps the resource server to distinguish between JWT access tokens and OpenID 
Connect ID Tokens. 


Authorization servers should prevent scenarios where clients can affect the value of the "sub" 
claim in ways that could confuse resource servers. For example, if the authorization server elects 
to use the client_id as the "sub" value for access tokens issued using the client credentials grant, 
the authorization server should prevent clients from registering an arbitrary client_id value, as 
this would allow malicious clients to select the sub of a high-privilege resource owner and confuse 
any authorization logic on the resource server relying on the "sub" value. For more details, please 
refer to Section 4.14 of [OAuth2.Security.BestPractices]. 


To prevent cross-JWT confusion, authorization servers MUST use a distinct identifier as an "aud" 
claim value to uniquely identify access tokens issued by the same issuer for distinct resources. For 
more details on cross-JWT confusion, please refer to Section 2.8 of [RFC8725]. 


Authorization servers should use particular care when handling requests that might lead to 
ambiguous authorization grants. For example, if a request includes multiple resource indicators, 
the authorization server should ensure that each scope string included in the resulting JWT access 
token, if any, can be unambiguously correlated to a specific resource among the ones listed in the 
"aud" claim. The details on how to recognize and mitigate this and other ambiguous situations is 
highly scenario dependent and hence is out of scope for this profile. 


Authorization servers cannot rely on the use of different keys for signing OpenID Connect ID 
Tokens and JWT tokens as a method to safeguard against the consequences of leaking specific 
keys. Given that resource servers have no way of knowing what key should be used to validate 
JWT access tokens in particular, they have to accept signatures performed with any of the keys 
published in AS metadata or OpenID Connect discovery; consequently, an attacker just needs to 
compromise any key among the ones published to be able to generate and sign JWTs that will be 
accepted as valid by the resource server. 
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6. Privacy Considerations 


As JWT access tokens carry information by value, it now becomes possible for clients and 
potentially even end users to directly peek inside the token claims collection of unencrypted 
tokens. 


The client MUST NOT inspect the content of the access token: the authorization server and the 
resource server might decide to change the token format at any time (for example, by switching 
from this profile to opaque tokens); hence, any logic in the client relying on the ability to read the 
access token content would break without recourse. The OAuth 2.0 framework assumes that 
access tokens are treated as opaque by clients. Administrators of authorization servers should 
also take into account that the content of an access token is visible to the client. Whenever client 
access to the access token content presents privacy issues for a given scenario, the authorization 
server needs to take explicit steps to prevent them. 


In scenarios in which JWT access tokens are accessible to the end user, it should be evaluated 
whether the information can be accessed without privacy violations (for example, if an end user 
would simply access his or her own personal information) or if steps must be taken to enforce 
confidentiality. 


Possible measures to prevent leakage of information to clients and end users include: encrypting 
the access token, encrypting the sensitive claims, omitting the sensitive claims or not using this 
profile, and falling back on opaque access tokens. 


In every scenario, the content of the JWT access token will eventually be accessible to the 
resource server. It's important to evaluate whether the resource server gained the proper 
entitlement to have access to any content received in the form of claims, for example, through 
user consent in some form, policies and agreements with the organization running the 
authorization servers, and so on. For example, a user might not wish to consent to granting given 
resource server information about any of the non-mandatory claims enumerated in Section 2 
(and its subsections). 
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This profile mandates the presence of the "sub" claim in every JWT access token, making it 
possible for resource servers to rely on that information for correlating incoming requests with 
data stored locally for the authenticated principal. Although the ability to correlate requests 
might be required by design in many scenarios, there are scenarios where the authorization 
server might want to prevent correlation. The "sub" claim should be populated by the 
authorization servers according to a privacy impact assessment. For instance, if a solution 
requires preventing tracking of principal activities across multiple resource servers, the 
authorization server should ensure that JWT access tokens meant for different resource servers 
have distinct "sub" values that cannot be correlated in the event of resource server collusion. 
Similarly, if a solution requires preventing a resource server from correlating the principal's 
activity within the resource itself, the authorization server should assign different "sub" values for 
every JWT access token issued. In turn, the client should obtain a new JWT access token for every 
call to the resource server to ensure that the resource server receives different "sub" and "jti" 
values at every call, thus preventing correlation between distinct requests. 


7. IANA Considerations 


7.1. Media Type Registration 


7.1.1. Registry Content 


This section registers "application/at+jwt", a new media type [RFC2046] in the "Media Types" 
registry [[ANA.MediaTypes] in the manner described in [RFC6838]. It can be used to indicate that 
the content is an access token encoded in JWT format. 


Typename: Application 
Subtypename: at+jwt 

Required parameters: N/A 
Optional parameters: N/A 


Encoding considerations: Binary; JWT values are encoded as a series of base64url-encoded 
values (with trailing '=' characters removed), some of which may be the empty string, 
separated by period ('.') characters. 


Security considerations: See the Security Considerations section of RFC 9068. 
Interoperability considerations: N/A 
Published specification: RFC 9068 


Applications that use this media type: Applications that access resource servers using OAuth 2.0 
access tokens encoded in JWT format 


Fragment identifier considerations: N/A 


Additional information: 
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Magic number(s): N/A 
File extension(s): N/A 
Macintosh file type code(s): N/A 


Person & email address to contact for further information: 
Vittorio Bertocci <vittorio@auth0.com> 


Intended usage: COMMON 

Restrictions on usage: None 

Author: Vittorio Bertocci <vittorio@auth0.com> 
Change controller: IETF 


Provisional registration? No 


7.2. Claims Registration 


Section 2.2.3.1 of this specification refers to the attributes "roles", "groups", "entitlements" defined 
in [RFC7643] to express authorization information in JWT access tokens. This section registers 
those attributes as claims in the "JSON Web Token (JWT)" IANA registry introduced in [RFC7519]. 


7.2.1. Registry Content 


7.2.1.1. Roles 


Claim Name: roles 

Claim Description: Roles 

Change Controller: IETF 

Specification Document(s): Section 4.1.2 of [RFC7643] and Section 2.2.3.1 of RFC 9068 


7.2.1.2. Groups 


Claim Name: groups 

Claim Description: Groups 

Change Controller: IETF 

Specification Document(s): Section 4.1.2 of [RFC7643] and Section 2.2.3.1 of RFC 9068 


7.2.1.3. Entitlements 


Claim Name: entitlements 

Claim Description: Entitlements 

Change Controller: IETF 

Specification Document(s): Section 4.1.2 of [RFC7643] and Section 2.2.3.1 of RFC 9068 
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